home *** CD-ROM | disk | FTP | other *** search
/ Power Programmierung / Power-Programmierung (Tewi)(1994).iso / qtawk / qtawk.man < prev    next >
Text File  |  1990-11-04  |  38KB  |  887 lines

  1.  
  2. QTAwk  Version 4.20 10/10/90                         QTAwk
  3.  
  4.  
  5. Name
  6.  
  7.    QTAwk - Pattern Scanning and Processing Language
  8.    QTAwk - Version 4.20 10/10/90
  9.  
  10.  
  11. Synopsis
  12.  
  13.    qtawk [-f file | -ffile | "program"] [-Fstr] [var=text | file | - | -- ] ...
  14.  
  15.  
  16. DESCRIPTION
  17.  
  18. QTAwk scans  each input  file for  lines that  match any  of a    set of patterns
  19. specified in the  program.  With  each pattern in  the program there  can be an
  20. associated action  that will  be performed  when a  line of  a file matches the
  21. pattern.
  22.  
  23. The QTAwk program may be specified as a file with the -f option as:
  24.  
  25.     -ffilename.ext
  26.     -f filename.ext
  27.  
  28. in which case the QTAwk program is read from the named file.  If the file  does
  29. not  exist  then  an  error  message  will  be    printed.   Multiple 'f' options
  30. specifying program files may be used.    Each program file is read in the  order
  31. given and the total program consists of all files read.
  32.  
  33. The QTAwk program may also be specified as a single argument as:
  34.  
  35.     "{ for (i in ARGV) printf ("%d: %s\n", i, ARGV[i]); }"
  36.  
  37. If the -f option is selected the full path/name/extension must be specified.
  38.  
  39. Files are read in order, the file name '-' means standard input.  Each line  is
  40. matched against  the pattern  portion of  every pattern/action    statement.  The
  41. associated  action  is    performed  for    each  matched  pattern.
  42.  
  43. A command line argument of "--" will stop the scan for more options.
  44.  
  45. If a file name has the form variable=value or "variable = value", the  variable
  46. named is set to the value specified.  Program variables may be changed before a
  47. file is read.  The assignment takes place when the argument would be treated as
  48. the next file to read.    "variable" must be a variable name defined in the QTAwk
  49. program.
  50.  
  51.    qtawk "{ print code, NR, $0 }" code=10 file1 code=75 file2
  52.  
  53. No assignment will happen before a BEGIN block, however an assignment after the
  54. last file will occur before any END block unless an exit was performed.
  55.  
  56. If no files are specified the input is read from standard input.
  57.  
  58. An input line is made  up of fields separated by  the field separator FS.   The
  59. fields are denoted  by $1, $2,    ..., $NF.   NF equals the  number of fields the
  60. input record has been split to make.  $0 denotes the entire line:
  61.  
  62.    $0 = "now is the time"
  63.  
  64.    $1 = "now"      $2 = "is"       $3 = "the"      $4 = "time"
  65.  
  66. with the default  FS = {_w},  white space.   If the field  separator is set  to
  67. comma, ',' with "-F," on the command  line or "FS=','" on the command line,  or
  68. in the program, then the fields might be:
  69.  
  70.     $0 = "a, b,c,, ,"
  71.  
  72.     $1 = "a"        $2 = " b"       $3 = "c"        $4 = ""
  73.     $5 = " "        $6 = ""
  74.  
  75. A pattern-action statement has the form:
  76.  
  77.     pattern { action }
  78.  
  79. A missing { action }  has the same effect as  { print $0; }, a    missing pattern
  80. always matches.
  81.  
  82. A pattern  is a  test that  is performed  on each  input line.     If the pattern
  83. matches the input line then the corresponding action is performed.
  84.  
  85. Patterns come in several forms:
  86.  
  87. Form        Example          Meaning
  88.  
  89. BEGIN        BEGIN {N=1;}      initialize N before input is read
  90. INITIAL     INITIAL {G=0;)    initialize G before input from each file
  91. NOMATCH     NOMATCH (G++;}    increment G for each line not matched
  92. FINAL        FINAL {print G;}  print G after each file
  93. END        END {print NR}    print NR after all input is read
  94. function    function x(y)     define a function called x
  95. text match  /stop/          line contains the string "stop"
  96. expression  $1 == 3          first field is the number 3
  97. compound    /x/ && NF > 2     more that two fields and contain "x"
  98. range        FNR==10,FNR==20   records ten through twenty inclusive
  99.  
  100. BEGIN, INITIAL, NOMATCH, FINAL and END patterns are special patterns that match
  101. respectively:  before  any files are  opened, after opening  each file, when  a
  102. line fails all patterns, after reading the last line in each file and after all
  103. files have been closed.  There may be multiple occurances of these patterns and
  104. the associated actions are executed in the order that they occur.
  105.  
  106. If there is  only a series  of BEGIN blocks  in the QTAwk  program and no other
  107. pattern/action blocks  except function    declarations, they  are executed before
  108. reading from the standard input.  If  only END blocks are defined then all  the
  109. files are read and NR will be set to the number of records in all the files.
  110.  
  111.     BEGIN { page = 5 }
  112.  
  113. A  function  pattern  is  never  matched  and  serves to declare a user defined
  114. function.
  115.  
  116.     function show(a) {local i; for (i in a) print a[i];}
  117.  
  118. A  user  defined  function  may  have  a  variable  number of arguments defined
  119. following the C convention:
  120.  
  121.     function max(...) {
  122.         local i, maxa = vargv[1];
  123.  
  124.         for ( i in vargv ) if ( vargv[i] > maxa ) maxa = vargv[i];
  125.         return maxa;
  126.     }
  127.  
  128. The variable arguments are accessed through the built-in variables vargc == the
  129. number of variable arguments passed, and vargv == an array with element indices
  130. 1 through vargc, each element is an argument passed.
  131.  
  132. A regular expression by itself is  matched against the input record, $0.   That
  133. is "/abc/" is equivalent to "$0 ~~ /abc/".
  134.  
  135. Any expression will match if it  evaluates to a non-zero numeric or  a non-null
  136. string.  Also  any logical combination    of expressions and  regular expressions
  137. may be used as a pattern.
  138.  
  139.     FILENAME != oldname && FILENAME != "skip"
  140.  
  141. The last special pattern is two expressions separated by a comma.  This pattern
  142. specifies a range  of records that  match the pattern.     The pattern  starts to
  143. match when the first pattern matches and stops matching when the second pattern
  144. matches.  If  they both match  on the same  input record then  only that record
  145. will match the pattern.
  146.  
  147.     /AUTHOR/,/NOTES/
  148.  
  149. An  action  is    a  sequence  of  statements  that  are performed when a pattern
  150. matches.
  151.  
  152. A statement can be one of the following:
  153.     # simple statement
  154.     STATEMENT
  155.  
  156.     # compound statement
  157.     { STATEMENT; STATEMENT; STATEMENT; STATEMENT; ... }
  158.  
  159.     # simple expression
  160.     EXPRESSION
  161.     # expression list - expressions separated by the sequence operator
  162.     EXPRESSION, EXPRESSION, EXPRESSION, ...
  163.  
  164.     print EXPRESSION_LIST;
  165.     print( EXPRESSION_LIST );
  166.  
  167.     printf FORMAT ;
  168.     printf FORMAT ,EXPRESSION_LIST ;
  169.     printf(FORMAT );
  170.     printf(FORMAT ,EXPRESSION_LIST );
  171.  
  172.     fprint(filename,EXPRESSION_LIST);
  173.  
  174.     fprintf(filename,FORMAT );
  175.     fprintf(filename,FORMAT ,EXPRESSION_LIST );
  176.  
  177.     getline( );
  178.     getline( variable );
  179.  
  180.     fgetline(filename);
  181.     fgetline(filename ,variable );
  182.  
  183.     if ( EXPRESSION_LIST ) STATEMENT
  184.     if ( EXPRESSION_LIST ) STATEMENT else STATEMENT
  185.  
  186.     for ( VARIABLE in ARRAY ) STATEMENT
  187.     for ( EXPRESSION_1 ; EXPRESSION_2 ; EXPRESSION_3 ) STATEMENT
  188.  
  189.     while ( EXPRESSION ) STATEMENT
  190.  
  191.     do STATEMENT while ( EXPRESSION );
  192.  
  193.     switch ( EXPRESSION ) {
  194.         case EXPRESSION_1: STATEMENT
  195.         case EXPRESSION_2: STATEMENT
  196.         default:           STATEMENT
  197.     }
  198.  
  199.     break;
  200.  
  201.     continue;
  202.  
  203.     cycle;
  204.  
  205.     delete variable[i];
  206.  
  207.     deletea variable;
  208.  
  209.     endfile;
  210.  
  211.     exit ;
  212.     exit EXPRESSION_LIST ;
  213.  
  214.     local variable_list;
  215.     local variable_list = value;
  216.  
  217.     next;
  218.  
  219.     return ;
  220.     return EXPRESSION ;
  221.  
  222. A  Compound  Statement    is  a  list  of  statements separated by semicolons and
  223. enclosed within braces, "{}".  White space is ignored beyond delimiting tokens.
  224. Thus,  statements  may    be  split  across  lines  where,  or  as necessary, for
  225. readability:
  226.  
  227.     {
  228.         print "value:", i,
  229.           "number:", j;
  230.         i = i + $3; j++;
  231.     }
  232.  
  233. An EXPRESSION_LIST is any number of valid expressions separated by the sequence
  234. operator, the comma ','.
  235.  
  236. Expressions take on string or numeric values depending on the operators.  There
  237. is only one string  operator, concatenation, indicated by  adjacent expressions
  238. or the symbol ∩ (extended ASCII hexadecimal 0xef, decimal 239).  The  following
  239. are the operators in order of increasing precedence:
  240.  
  241. Operation        Operator      Example     Meaning
  242.  
  243. sequence        ,          x=2,y=3;    assign 3 to y then assign 2 to x
  244.  
  245. assignment        =          x = 2       two is assigned to x
  246. assignment        ^= *= /=      x += 2      two is added to x
  247.             %= += -=
  248.             &= |= @=
  249.             <<= >>= ∩=
  250.  
  251. conditional        ? :       x ? y : z   if x then y else z
  252. logical OR        ||          x || y      if (x) 1, else if (y) 1, else 0
  253. logical AND        &&          x && y      if (x) if (y) 1, else 0, else 0
  254. bit-wise XOR        @          x @ y       x XOR y
  255. bit-wise OR        |          x | y       x OR y
  256. bit-wise AND        &          x & y       x AND y
  257. array membership    in          x in y      if ( exists(y[x]) ) 1 else 0
  258. matching        ~~ !~      $1 ~~ /x/   if ($1 contains x) 1 else 0
  259. equality        == !=      x == y      if (x equals y) 1 else 0
  260. relational        < <= >= >      x < y       if (x less than y) 1 else 0
  261.             <= >= <
  262. bit shift        << >>      x << 2      shift value of x 2 bits left
  263. concatenation              "x" "y"     a new string "xy"
  264. concatenation        ∩          "x" ∩ "y"   a new string "xy"
  265. add, subtract        +  -      x + y       sum of x and y
  266. mul, div, mod        * / %      x * y       product of x and y
  267. exponentiation        ^          x^y          x to the yth power
  268. unary plus minus    + -       -x          negative of x
  269. inc/dec         ++ --      x++          x then add 1 to x
  270. logical not        !          !x          if (x is 0 or null) 1 else 0
  271. tag            $$          $$0          the string matched in the pattern
  272. field            $          $3          the 3rd field
  273. subscripting        []          x[2]          element 2 of x
  274. grouping        ()          ($1)++      increment the 1st field
  275.  
  276. Variables may  be scalars,  array elements  (denoted x[i])  or fields  (denoted
  277. $expression).  Variable names begin with a letter or underscore and may contain
  278. any number of letters, digits, or underscores.
  279.  
  280. Array subscripts may  be any integer  or string.   Multi-dimensional arrays are
  281. supported by QTAwk and accessed in the C manner:  x[2][1]
  282.  
  283. Variables are initialized  to both zero  and the null  string.    Fields    and the
  284. command  line  arguments  will    be  both  string  and  numeric    if  they can be
  285. completely represented as numbers.  The range for numbers is 1E-306 ... 1E306.
  286.  
  287. for  numeric  operations,  if  both  operands  are  integers,  the result is an
  288. integer.  Thus, 3 / 2 is 1, but 3.0 / 2 is 1.5.
  289.  
  290. Comparison will  be numeric  if both  operands are  numeric otherwise  a string
  291. comparison will be  made.  Operands  will be coerced  to strings if  necessary.
  292. Uninitialized variables will compare as numeric if the other operand is numeric
  293. or uninitialized.  Eg. 2 > "10" and 2 < 10.
  294.  
  295. There are a number of built in variables they are:
  296.  
  297. Variable    Meaning                     Default
  298.  
  299. _arg_chk    flag to check number of arguments         0
  300. ARGC        number of command line arguments         -
  301. ARGI        array of command line arguments          -
  302. ARGV        subscript value for next command line argument     -
  303. CYCLE_COUNT    Count of cycle statement             -
  304. DEGREES     degree flag                     0
  305. ENVIRON     array of environment strings             -
  306. FALSE        false                         0
  307. FILENAME    name of current input file             -
  308. FNR        record number in current file             -
  309. FS        controls the input field separator         /{_z}+/
  310. LONGEST_EXP    Longest Expression                 1
  311. MAX_CYCLE    Max count of cycle statement             100
  312. NF        number of fields in current record         -
  313. NG        expression count                 -
  314. NR        number of records read so far             -
  315. OFMT        output format for records             "%.6g"
  316. OFS        output field separator                 " "
  317. ORS        output record separator              "\n"
  318. RETAIN_FS    Flag to retain Field Separator             0
  319. RS        controls input record separator          "\n"
  320. TRACE        Flag to Trace Statements             0
  321. TRANS_FROM    String Translation          "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  322. TRANS_TO    String Translation          "abcdefghijklmnopqrstuvwxyz"
  323. TRUE        true                         1
  324. CLENGTH     length of string matched in case statement     -
  325. CSTART        start of string match in case statement      -
  326. MLENGTH     length of string matched in pattern match     -
  327. MSTART        start of string match in pattern match         -
  328. RLENGTH     length of string matched by match function     -
  329. RSTART        start of string match by match function      -
  330. vargc        Variable Argument count              -
  331. vargv        Variable Argument array              -
  332.  
  333.  
  334. ARGC and ARGV  are the count  and an array  of the values  of the command  line
  335. arguments.  ARGI is  the index value for  the next command line  argument to be
  336. processed.  ARGV[0] is    the full path/name of  QTAwk.exe, and the rest    are all
  337. the command line arguments except any "-F", "-f" or "--" options.
  338.  
  339. The field separator may set to a single character or a string.    If a string, it
  340. is interpreted as a  regular expression and converted  to internal form at  the
  341. time of assignment.   A single    space has a  special meaning and  is changed to
  342. /{_z}+/.  A BEGIN action may be used  to set the separator or it may be  set by
  343. using the -F command line option or as a command line variable.
  344.  
  345.     BEGIN { FS = ",";}      sets FS to a single comma
  346.     "-F/[ ]/"               sets FS to a single space
  347.     "FS=/[ ]/"              sets FS to a single space
  348.  
  349. The record separator, RS,  may be a single  character or string.   If a string,
  350. then it interpreted as a regular  expression and converted to internal form  at
  351. the time of assignment.  Any string matching the regular expression, becomes  a
  352. record separator.   The  null string,  RS =  "", will  set RS  == /\n\n/, i.e.,
  353. consecutive newlines delimit records.
  354.  
  355. There are a number of built in functions:
  356.  
  357. Function        Value returned
  358.  
  359. acos(x)         arc-cosine of x
  360. asin(x)         arc-sine of x
  361. atan2(x,y)        arctangent of x/y        in the range -π to π
  362. center(s,w)        string s centered        center("abc",75)
  363. center(s,w,c)        string s centered        center("abc",75,'-')
  364. copies(s,n)        n copies of s        copies('=',45)
  365. cos(x)            cosine of x         x in radians/degrees
  366. cosh(x)         hyperbolic cosine of x
  367. deletec(s,p,n)        deletec n characters at p    deletec("abcdef",2,2)
  368. e_type(exp)        expression type        in range 0 to 5
  369. execute(s)        value of expression in s    execute string
  370. execute(s,se)        value of expression in s    execute string
  371. execute(s,se,rf)    value of expression in s    execute string
  372. execute(a)        value of expression in s    execute array
  373. execute(a,se)        value of expression in s    execute array
  374. execute(a,se,rf)    value of expression in s    execute array
  375. exp(x)            exponentiation of x     (e ^ x)
  376. fract(x)        fractional portion of x
  377. gsub(r,s)        number of substitutions    substitute s for all r in $0
  378. gsub(r,s,t)        number of substitutions    substitute s for all r in t
  379. index(s,t)        position of t in s        0 if not in s
  380. insert(s1,s2,p)     string s1 with s2 inserted    insert("ad","bc",2)
  381. int(x)            integer portion of x
  382. justify(a,n,w)        elements array a as string    justified to width w
  383. justify(a,n,w,c)    elements array a as string    justified to width w
  384. length            number of characters in $0
  385. length(s)        number of characters in s
  386. log(x)            natural logrithm of x
  387. log10(x)        logrithm base 10 of x
  388. match(s,r)        position of r in s or 0    sets RSTART and RLENGTH
  389. overlay(s1,s2.p)    string s1 with s2 overlayed overlay("abc","def",4)
  390. pd_sym(name)        pre-defined symbol with name equal to string name
  391. pd_sym(name)        pre-defined symbol with position in symbol table == n
  392. pi            π                3.14159...
  393. pi()            π                3.14159...
  394. rand()            random number        0 <= rand < 1
  395. remove(s,c)        string s with c's removed   remove("===s===",'=')
  396. replace(s)        string s with sub-expressions replaced
  397. rotate(a)        rotated array a
  398. sdate(f)        current system date formated as string
  399. sin(x)            sine of x            x in radians/degrees
  400. sinh(x)         hyperbolic sine of x
  401. split(s,a)        number of fields        split s into a on FS
  402. split(s,a,fs)        number of fields        split s into a on fs
  403. sprintf(f,e,...)    formatted string
  404. srange(c1,c2)        string from c1 to c3 inclusive
  405. srev(s)         string s with characters reversed
  406. sqrt(x)         square root of x
  407. srand(seed)        random number generator seed
  408. stime(f)        current system time formatted as string
  409. stran(s)        string s with characters translated
  410. stran(s,st)        string s with characters translated
  411. stran(s,st,sf)        string s with characters translated
  412. strim(s)        string s with leading & trailing white space removed
  413. strim(s,le)        string s with leading expression and trailing
  414.              white space removed
  415. strim(s,le,te)        string s with leading & trailing expression removed
  416. strlwr(s)        s tranlated to lower case
  417. strupr(s)        s tranlated to upper case
  418. sub(r,s)        number of substitutions    substitute s for one r in $0
  419. sub(r,s,t)        number of substitutions    substitute s for one r in t
  420. substr(s,p)        substring of s from p to end
  421. substr(s,p,n)        substring of s from p of length n
  422. system(s)        exit status         execute command s
  423. ud_sym(name)        user-defined symbol with name equal to string name
  424. ud_sym(name)        user-defined symbol with position in symbol table == n
  425.  
  426. The numeric function srand(x) sets a new seed for the random number  generator.
  427. srand() sets the seed from the current system time.
  428.  
  429. The regular expression arguments  of sub, gsub, match  and strim may be  either
  430. regular expressions delimited by slashes or  any expression.  If not a    regular
  431. expression, the expression is coerced to  a string and the resulting string  is
  432. converted into a regular expression.  This coersion and conversion occurs every
  433. time the  procedure is    called so  the regular    expression form  will always be
  434. faster.
  435.  
  436. The print, printf and fprintf statements come in several forms:
  437.  
  438. Form                Meaning
  439.  
  440. print;                print $0 on standard output
  441. print expression, ...;        prints expressions separated by OFS
  442. print(expression, ...);     prints expressions separated by OFS
  443. printf format, expression, ...; prints expressions formated by "format"
  444. printf(format, expression, ...);prints expressions formated by "format"
  445. fprint file;            print $0 to "file"
  446. fprint(file);            print $0 to "file"
  447. fprint file,expression, ...;    prints expressions separated by OFS to "file"
  448. fprint(file,expression, ...);    prints expressions separated by OFS to "file"
  449. fprintf file,format,expression, ...;
  450.                 prints expressions formated by
  451.                 "format" to "file"
  452. fprintf(file,format,expression, ..);
  453.                 prints expressions formated by
  454.                 "format" to "file"
  455.  
  456. close(file)            close "file"
  457.  
  458. The [f]print  statement prints    its arguments  on the  standard output,  or the
  459. specified file, separated by the current output field separator, and terminated
  460. by  the  output  record  separator.    The  [f]printf  statement  formats   its
  461. expression-list according to the format.   The file is only opened once  unless
  462. it is closed  between executions of  the fprint[f] statement.    A file    that is
  463. open for  output must  be closed  if it  is to    be used  for input.  The "file"
  464. argument may be any expression that evaluates to a DOS file name.
  465.  
  466. There are two functions used for input:
  467.  
  468. Form            Meaning
  469.  
  470. getline         read the next record into $0
  471. getline s        read the next record into s
  472. getline(s)        read the next record into s
  473. fgetline(file)        read a record from "file" into $0
  474. fgetline(file,s)    read a record from "file" into s
  475. getc()            read a single character from current input file
  476. fgetc(file)        read a single character from "file"
  477.  
  478. [f]getline returns -1 if  there is an error  (such as non existent  file), 0 on
  479. end of file and the number of characters read otherwise.
  480.  
  481. The current input line and fields and  variables NF, NR and FNR are set  by the
  482. forms of [f]getline according to the following table:
  483.  
  484.       │ getline();
  485.       │ getline;   getline(v);   fgetline(F);   fgetline(F,v);
  486.    ───────┼───────────────────────────────────────────────────────
  487.    $0      │   set      not set         set        not set
  488.    $i      │   set      not set         set        not set
  489.    NF      │   set      not set         set        not set
  490.    NR      │   set       set         not set        not set
  491.    FNR      │   set       set         not set        not set
  492.  
  493. [f]getc returns the character read or -1 on a read error. 0 is returned if  the
  494. end of file is reached.  If the current input file, for 'getc', or "file",  for
  495. 'fgetc', is the standard input file  and has not been redirected away  from the
  496. keyboard, either function will return  zero, 0, for keystrikes which  cannot be
  497. represented by an ASCII  character.  A second  call must be made  to obtain the
  498. extended ASCII character.  If the second call also returns zero, then an end of
  499. file has been reached.
  500.  
  501. The "for ( i in a )" statement  assigns to i the indices of a for  all elements
  502. in a. The sequencing of the values  of i start with any integer values,  low to
  503. high, then any string values  following the ASCII collating sequence  (the same
  504. sequence as used by the C strcmp functions.
  505.  
  506. The "while ()", "do  ... while ()", "for  (;;)", break and continue  statements
  507. are as    in C.  the switch/case    statements are    as in  C, except that that case
  508. labels may be any valid QTAwk expression list.    The following logic is followed
  509. in matching case labels to the switch expression value:
  510.  
  511.    if ( case_label_value == regular expression )
  512.        switch_value ~~ case_label_value
  513.     else switch_value == case_label_value
  514.  
  515. The next statement stops processing the pattern/action statements, reads in the
  516. next record and restarts the patterns/actions with the first.
  517.  
  518. The cycle  statement will  check the  current value  of CYCLE_COUNT against the
  519. value  of  MAX_CYCLE  and  perform  the  following  actions:    (CYCLE_COUNT is
  520. initialized to 1 every time a new record in read from the current input file)
  521.  
  522.     1. CYCLE_COUNT >  MAX_CYCLE --> perform same action as "next"
  523.        statement.
  524.     2. CYCLE_COUNT <= MAX_CYCLE --> increment CYCLE_COUNT and restart
  525.        pattern/action processing with current values of NF, NR, FNR,
  526.        $0 and $i, 1 <= i <= NF
  527.  
  528. An  exit  statement  will  cause  the  END  actions  to  be  performed    or if
  529. encountered  in  an  END  action  will    cause  termination of the program.  The
  530. optional  expression  is  returned  as    the  exit status unless overridden by a
  531. further exit statement in an END action.
  532.  
  533. An endfile statement simulates an end-of-file  on the current input file.   Any
  534. remaining pattern/action pairs are skipped  and any FINAL actions are  executed
  535. before proceesing the next command line argument.
  536.  
  537. The return statement may be used only in function declarations.  It may have an
  538. optional value which is returned as the value of the function.    The value of  a
  539. function defaults to zero/null string (0/"").
  540.  
  541. REGULAR EXPRESSIONS
  542.  
  543.     ^ matches Beginning of Line as first character of expression
  544.     $ matches End of Line as last character of expression
  545.     \c matches following (hexadecimal value shown in parenthesis):
  546.        \a == bell (alert)    ( \x07 )
  547.        \b == backspace         ( \x08 )
  548.        \f == formfeed         ( \x0c )
  549.        \n == newline         ( \x0a )
  550.        \r == carriage return ( \x0d )
  551.        \s == space         ( \x20 )
  552.        \t == horizontal tab  ( \x09 )
  553.        \v == vertical    tab  ( \x0b )
  554.        \c == c [ \\ == \ ]
  555.        \ooo == character represented by octal value ooo
  556.            1 to 3 octal digits acceptable
  557.        \xhh == character represented by hexadecimal value hh
  558.            1 or 2 hexadecimal digits acceptable
  559.     . matches any character
  560.     [abc0-9] Character Class - match any character in class
  561.     [^abc0-9] Negated Character Class - match any character not in class
  562.     [!abc0-9] Negated Character Class - match any character not in class
  563.     [#abc0-9] Matched Character Class - for second match, class character
  564.           must match in corresponding position
  565.     * - Closure, Zero or more matches
  566.     + - Positive Closure, One or More matches
  567.     ? - Zero or One matches
  568.     r(s)t embedded regular expression s
  569.     r|s|t  '|' == logical 'or' operator. Expression r or s or t
  570.     @ - Look-Ahead, r@t, matches regular expression 'r' only when r  is
  571.     followed  by  regular  expression  't'.    Regular expression t not
  572.     contained  in  final  match.    Symbol    loses  special meaning when
  573.     contained within parenthesis, '()', or character class, '[]'.
  574.     r{n1,n2} - at least n1 and up to n2 repetitions of expression r
  575.      n1, n2 integers with 1 <= n1 <= n2
  576.      r{2,6} ==> rrr?r?r?r?
  577.      r{3,3} ==> rrr
  578.      Expressions grouped by ", (), [], or names, "{name}"
  579.      repeated as a group: (Note the treatment of quoted expressions)
  580.      (r){2,6} ==> (r)(r)(r)?(r)?(r)?(r)?
  581.      [r]{2,6} ==> [r][r][r]?[r]?[r]?[r]?
  582.      {r}{2,6} ==> {r}{r}{r}?{r}?{r}?{r}?
  583.      "r"{2,6} ==> "rr(r)?(r)?(r)?(r)?"
  584.     {named_expr} - named expression.   In regular expressions  "{name}"
  585.     is replaced by the value  of the corresponding variable.   Unrecognized
  586.     variable names are not replaced.  Names starting with an underscore and
  587.     followed  by  a  single  upper  or    lower  case  letter are reserved as
  588.     predefined.  The following predefined names are currently available:
  589.     {_a} == [A-Za-z]            Alphabetic
  590.     {_b} == [{}()[]<>]            Brackets
  591.     {_c} == [\x001-\x01f\x-7f]        Control character
  592.     {_d} == [0-9]            Digit
  593.     {_e} == [DdEe][-+]?{_d}{1,3}    Exponent
  594.     {_f} == [-+]?({_d}+\.{_d}*|{_d}*\.{_d}+)     Floating point number
  595.     {_g} == {_f}({_e})?         float, optional exponent
  596.     {_h} == [0-9A-Fa-f]         Hex-digit
  597.     {_i} == [-+]?{_d}+            Integer
  598.     {_n} == [A-Za-z0-9]         alpha-Numeric
  599.     {_o} == [0-7]            Octal digit
  600.     {_p} == [\!-/:-@[-`{-\x07f]     Punctuation
  601.     {_q} == {_s}[\"']               double or single Quote
  602.     {_r} == {_f}{_e}            Real number
  603.     {_s} == (^|[!\\](\\\\)*)        zero or even number of Slashes
  604.     {_t} == [\s-~]            printable character
  605.     {_u} == [\!-~]            graphical character
  606.     {_w} == [\s\t]            White space
  607.     {_z} == [\t-\r\s]            space, \t, \n, \v, \f, \r, \s
  608.  
  609. PRINTF FORMAT
  610.  
  611. QTAwk follows the ANSI standard for the C Language for the format string in the
  612. printf and fprintf functions  except for the 'P'  and 'n' types, which  are not
  613. supported and will give unpredictable results.
  614.  
  615. A format specification has the form:
  616.  
  617.     %[flags][width][.precision][h | l | L]type
  618.  
  619. which is matched by the following regular expression:
  620.  
  621.     /%{flags}?{width}?{precision}?[hlL]?{type}/
  622.  
  623. with:
  624.  
  625. flags = /[-+\s#0]/;
  626. width = /({_d}+|\*)/;
  627. precision = /(\.({_d}+|\*))/;
  628. type = /[diouxXfeEgGcs]/;
  629.  
  630. Each  field  of  the  format  specification  is  a single character or a number
  631. signifying a particular format option.    The type character, which appears after
  632. the last optional format field,  enclosed in braces '[..]', determines  whether
  633. the associated argument is interpreted as  a character, a string, or a    number.
  634. The simplest  format specification  contains only  the percent    sign and a type
  635. character (for example, %s).  The optional fields control other aspects of  the
  636. formatting, as follows:
  637.  
  638. flags  ==>  Control  justification  of    output    and  printing of signs,
  639.         blanks, decimal points, octal and hexadecimal prefixes.
  640.  
  641. width ==> Control minimum number of characters output.
  642.  
  643. precision ==> Controls maximum number of characters printed for all  or
  644.           part of the output field,  or minimum number of digits  printed
  645.           for integer values.
  646.  
  647. h, l,  L ==>  Prefixes that  determine size  of argument expected (this
  648.           field is retained only for compatibility to C format strings).
  649.  
  650. h ==> Used  as a prefix  with the integer  types d, i,    o, x, and  X to
  651.       specify that  the argument  is short  int, or  with u  to specify a
  652.       short unsigned int
  653.  
  654. l == > Used as    a prefix with d, i,  o, x, and X types    to specify that
  655.        the argument is long int, or with u to specify a long unsigned int;
  656.        also used as  a prefix with  e, E, f,  g, and G    types to specify a
  657.        double, rather than a float
  658.  
  659. L ==> Used as a prefix with e,    E, f, g, and G types to specify  a long
  660.       double
  661.  
  662. If a percent  sign, '%', is  followed by a  character that has  no meaning as a
  663. format field, the character  is simply copied to  the output.  For  example, to
  664. print a percent-sign character, use "%%".
  665.  
  666. Type characters:
  667.  
  668. d ==> integer, Signed decimal integer
  669. i ==> integer, Signed decimal integer
  670. u ==> integer, Unsigned decimal integer
  671. o ==> integer, Unsigned octal integer
  672. x ==> integer, Unsigned hexadecimal integer, using "abcdef"
  673. X ==> integer, Unsigned hexadecimal integer, using "ABCDEF"
  674. f ==> float, Signed value  having the form [-]dddd.dddd, where    dddd is
  675.       one  or  more  decimal  digits.     The  number of digits before the
  676.       decimal  point  depends  on  the    magnitude  of the number, and the
  677.       number of digits after the  decimal point depends on the    requested
  678.       precision.
  679. e ==> float, Signed value having the form [-]d.dddd e [sign]ddd,  where
  680.       d is a single  decimal digit, dddd is  one or more decimal  digits,
  681.       ddd is exactly three decimal digits, and sign is + or -.
  682. E ==> float, Identical    to the e format,  except that E introduces  the
  683.       exponent instead of e.
  684. g ==> float, Signed value printed  in f or e format, whichever    is more
  685.       compact for the given  value and precision.   The e format is  used
  686.       only when the exponent of the value is less than -4 or greater than
  687.       the  precision  argument.    Trailing  zeros  are truncated and the
  688.       decimal point appears only if one or more digits follow it.
  689. G ==> float, Identical    to the g format,  except that G introduces  the
  690.       exponent (where appropriate) instead of e.
  691. c ==> character, Single character
  692. s ==> string, Characters printed up to the first null character  ('\0')
  693.       or until the precision value is reached.
  694.  
  695. Flag Characters
  696.  
  697. - ==> Left justify the result  within the given field width.   Default:
  698.       Right justify.
  699.  
  700. + ==> Prefix the output value with a sign (+ or -) if the output  value
  701.       is of  a signed  type.   Default:   Sign appears    only for negative
  702.       signed values (-).
  703.  
  704. blank ('  ') ==>  Prefix the  output value  with a  blank if the output
  705.     value is signed  and positive.     The blank is  ignored if both    the
  706.     blank and + flags appear.  Default:  No blank.
  707.  
  708. # ==> When  used with the  o, x, or  X format, the  # flag prefixes any
  709.       nonzero output value with 0, 0x, or 0X, respectively.  Default:  No
  710.       blank.
  711.  
  712. # ==>  When used  with the  e, E,  or f  format, the  # flag forces the
  713.        output value  to contain  a decimal  point in  all cases.  Default:
  714.        Decimal point appears only if digits follow it.
  715.  
  716. # ==> When used with  the g or G format,  the # flag forces the  output
  717.       value to    contain a  decimal point  in all  cases and  prevents the
  718.       truncation of trailing zeros.  Default:  Decimal point appears only
  719.       if digits follow it.  Trailing zeros are truncated.
  720.  
  721. # ==> Ignored when used with c, d, i, u or s
  722.  
  723. 0 ==> For  d, i, o,  u, x, X,  e, E, f,  g, and G  conversions, leading
  724.       zeros (following any indication of sign or base) are used to pad to
  725.       the field width;    no space padding  is performed.   If the 0  and -
  726.       flags both appear, the 0 flag will be ignored.  For d, i, o, u,  x,
  727.       and X conversions, if a precision is specified, the 0 flag will  be
  728.       ignored.      For  other  conversions  the    behavior  is   undefined.
  729.       Default:    Use blank padding
  730.  
  731. If the    argument corresponding    to a  floating-point specifier    is infinite  or
  732. indefinite, the following output is produced:
  733.  
  734.        + infinity   ==> 1.#INFrandom-digits
  735.        - infinity   ==> -1.#INFrandom-digits
  736.        Indefinite   ==> digit.#INDrandom-digits
  737.  
  738. The width argument  is a non-negative  decimal integer controlling  the minimum
  739. number of characters printed.  If the number of characters in the output  value
  740. is less than the specified width, blanks are added to the left or the right  of
  741. the values (depending  on whether the  - flag is  specified) until the    minimum
  742. width is reached.  If  width is prefixed with a  0 flag, zeros are added  until
  743. the minimum width is reached (not useful for left-justified numbers).
  744.  
  745. The width specification never causes a value to be truncated; if the number  of
  746. characters in the output value is greater than the specified width, or width is
  747. not given, all characters  of the value are  printed (subject to the  precision
  748. specification).
  749.  
  750. The  width  specification  may    be  an    asterisk  (*), in which case an integer
  751. argument from the argument  list supplies the value.   The width argument  must
  752. precede the value being formatted in the argument list.  A nonexistent or small
  753. field  width  does  not  cause    a  truncation  of  a  field; if the result of a
  754. conversion is  wider than  the field  width, the  field expands  to contain the
  755. conversion result.
  756.  
  757. The precision  specification is  a non-negative  decimal integer  preceded by a
  758. period, '.', which specifies the number of characters to be printed, the number
  759. of decimal  places, or    the number  of significant  digits.   Unlike the  width
  760. specification,    the  precision    can  cause  truncation    of the output value, or
  761. rounding in the case of a floating-point value.
  762.  
  763. The precision specification may be an  asterisk, '*', in which case an  integer
  764. argument from  the argument  list supplies  the value.     The precision argument
  765. must precede the value being formatted in the argument list.
  766.  
  767. The interpretation of  the precision value,  and the default  when precision is
  768. omitted, depend on the type, as shown below:
  769.  
  770. d,i,u,o,x,X ==>  The precision    specifies the  minimum number  of digits  to be
  771.  printed.  If the number of digits in the argument is less than precision,  the
  772.  output value is  padded on the  left with zeros.   The value  is not truncated
  773.  when the number of digits exceeds precision.    Default:  If precision is 0  or
  774.  omitted entirely, or if the period (.) appears without a number following  it,
  775.  the precision is set to 1.
  776.  
  777. e, E ==> The precision specifies the  number of digits to be printed after  the
  778.  decimal  point.    The  last  printed    digit  is  rounded.   Default:    Default
  779.  precision is 6; if precision is 0  or the period (.) appears without a  number
  780.  following it, no decimal point is printed.
  781.  
  782. f ==>  The precision  value specifies  the number  of digits  after the decimal
  783.  point.  If a decimal point appears, at least one digit appears before it.  The
  784.  value is  rounded to  the appropriate    number of  digits.   Default:    Default
  785.  precision is  6; if  precision is  0, or  if the  period (.) appears without a
  786.  number following it, no decimal point appears.
  787.  
  788. g,  G  ==>  The  precision  specifies  the maximum number of significant digits
  789.  printed.  Default:  Six  significant digits are printed, without  any trailing
  790.  zeros that are truncated.
  791.  
  792. c ==>No effect.  Default:  Character printed
  793.  
  794. s ==> The precision specifies the  maximum number of characters to be  printed.
  795.  Characters in excess of precision are    not printed.  Default:    All  characters
  796.  of the string are printed.
  797.  
  798. EXAMPLES
  799.  
  800. Print lines longer than 72 characters (missing action is print):
  801.  
  802.     length($0) > 72
  803.  
  804. or
  805.  
  806.     length       > 72
  807.  
  808. Print first two fields in opposite order (missing pattern is always match):
  809.  
  810.     { print $2, $1; }
  811.  
  812. Add up first column, print sum and average:
  813.  
  814.         { s += $1; }
  815.     END    { print "sum is", s, "average is", s/NR }
  816.  
  817. Print fields in reverse order:
  818.  
  819.     { for ( i = NF ; i > 0 ; --i ) print $i; }
  820.  
  821. Print all lines between start/stop pairs:
  822.  
  823.     /start/,/stop/
  824.  
  825. Print all lines whose first field is different from previous one:
  826.  
  827.     $1 != prev { print; prev = $1; }
  828.  
  829. Convert date from MM/DD/YY to metric (YYMMDD):
  830.  
  831.     { n = split(sdate(0),a,"/"); date = a[3] ∩ a[1] ∩ a[2] }
  832.  
  833. Copy a C program and insert include files:
  834.  
  835.     $1 == "#include" && $2 ~~ /^"/ {
  836.         local tfile = $2;
  837.  
  838.         gsub(/"/, "",tfile);
  839.         while ( fgetline(tfile,tmp) > 0 ) print tmp;
  840.         next;
  841.     }
  842.     { print; }
  843.  
  844. AUTHOR
  845.  
  846. QTAwk
  847. Utility Creation Program
  848. Version 4.01 07-04-90
  849. (c) Copyright 1988 - 1990 Pearl Boldt.    All Rights Reserved.
  850.  
  851. All warranties as to this software, whether express or implied, are disclaimed,
  852. including without limitation any implied warranties of merchantability, fitness
  853. for a  particular purpose,  functionality or  data integrity  or protection are
  854. disclaimed.
  855.  
  856. You are free to use, copy and give to others QTawk for noncommercial use IF:
  857.  
  858.        => NO FEE IS CHARGED FOR USE, COPYING OR DISTRIBUTION.
  859.        => ALL FILES AND DOCUMENTATION ACCOMPANY THE PROGRAMS.
  860.        => THEY ARE NOT MODIFIED IN ANY WAY.
  861.  
  862. If you find QTAwk convenient to use, a registration of $35 would be appreciated.  If you send $50 or more you will receive, when available, the current and next version of the QTgrep, QSgrep and flagset programs and documentation.
  863.  
  864.    Pearl Boldt
  865.    13012 Birdale Lane
  866.    Darnestown, MD 20878
  867.  
  868. If  you  find  QTAwk  convenient  to  use,  a  registration  of  $35  would  be
  869. appreciated.  If you  send $50 or more    you will receive the  current and, when
  870. available, next version of the QTAwk program and documentation.
  871.  
  872. Questions may be sent to the address above or to
  873.    CompuServe ID:  72040.434
  874.  
  875. Site licenses are  available for QTAwk.   Inquires should  be addressed to  the
  876. copyright holder listed above or the CompuServe ID listed.
  877.  
  878. All inquires concerning the use and/or distribution of QTAwk, documentation and
  879. accompanying files should be addressed to the copyright holder listed above  or
  880. the CompuServe ID listed.
  881.  
  882. SEE ALSO:
  883.  
  884. A. V Aho, B. W Kernighan, P. J. Weinberger,
  885.     "The AWK Programming Language"
  886.     Addison-Wesley 1988   ISBN 0-201-07981-X
  887.